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PREFACE 


This manual describes the features and operation of the Link-11 Linker 
and the Libr-11 Librarian, both are system programs for the PDP-11 
Disk Operating System (DOS). The reader is expected to be familiar 
with the DOS Monitor and the DOS Assembler; as described in their re- 
spective documents listed on the preceding page. 

The manual has two major parts: 

Part I describes the Link-11 Linker 
Part II describes the Libr-11 Librarian 

A Master Table of Contents follows this page, and each major part 
begins with a separate detailed Table of Contents. Chapters are num- 
bered sequentially throughout the manual, and for quick reference pur- 
poses the manual is concluded with a comprehensive index. 

In addition to the Link^ll Linker and the Libr-11 Librarian, the 
Disk Operating System software includes: 

DOS Monitor 
FORTRAN IV 
PAL*-11R Assembler 
Edit-11 Text Editor 
0DT-11R Debugging Program 
PIP, File Utility Package 


The following conventions apply to subsequent examples : 


1. System program printout is underlined whereas user 
typed input is not. 

2. All command strings are terminated by typing the 

RETURN key, symbolized as <CR> 

3. Elements enclosed in parentheses are optional. 
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CHAPTER 1 


INTRODUCTION TO LINK-11 LINKER 


The PDP-11 Disk Operating System software includes the Link-11 Linker; 
a system program for linking and relocating user programs assembled by 
the DOS Assembler. Link-11 enables the user to separately assemble 
his main program and various subprograms without assigning an absolute 
address for each segment at assembly time. 


The binary output (object module) of each assembly can be pro- 
cessed by Link-11 to: 


• Relocate each object module and assign absolute ad- 
dresses. 

• Link the modules by correlating global symbols de- 
fined in one module and referenced in another module. 

• Produce a load map which displays the assigned abso- 
lute addresses. 

• Create a load module which can subsequently be loaded 
(by the Monitor or the Absolute Loader) and executed. 


The advantages of using Link-11 include: 


• The source program can be divided into segments (usually 
subroutines) and assembled separately. If an error is 
discovered in one segment, only that segment needs to 
be reassembled. Link-11 can then link the newly as- 
sembled object module with other object modules. 


• Absolute addresses need not be assigned at assembly 
time; the Linker automatically assigns absolute ad- 
dresses. This keeps programs from overlaying each 
other. This also allows subroutines to change size 
without influencing the placement of other routines. 


• Separate assemblies allow the total number of symbols 
to exceed the number allowed in a single assembly. 


• Internal symbols (which are not global) need not be 
unique among object modules. Thus, naming rules are 
required for global symbols only when different pro- 
grammers prepare separate subroutines for a single 
program. 
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Subroutines may be provided for general use in ob- 
ject module form to be linked into the user's pro- 
gram. 


Link-11 is designed to run on an 8K PDP-11 with a disk and a tele- 
printer. DECtape, high-speed paper tape reader and punch and a line 
printer may be used if available. The DECtape and the high-speed 
reader/punch significantly speed up the linking process. A line 
printer provides a fast display device for the load map listing. 

The instructions and assembler directives of the PAL-11R Assembler 
are used herein to describe the operation of Link-11. However, Link-11 
can link and relocate any object modules which conform to its linking 
format (consult your nearest DEC representative for the linking format) . 

1.1 ABSOLUTE AND RELOCATABLE PROGRAM SECTIONS 

A program assembled by PAL-11R can consist of an absolute program sec- 
tion, declared by the .ASECT assembler directive, and relocatable pro- 
gram sections, declared by the .CSECT assembler directive; without 
either the assembler assumes a .CSECT directive. The program and data 
in a relocatable section are assigned absolute addresses by the Linker 
such that the relocatable section is normally at the high end of mem- 
ory. The assignment of addresses can be influenced by command string 
options (see Section 3.2). The Linker appropriately modifies all in- 
structions and/or data as necessary to account for the relocation of 
the control section (as declared by .CSECT) . 

Link-11 handles the absolute section, as well as the named and 
unnamed control sections. The unnamed control section is internal to 
each object module. That is, every object module can have an unnamed 
control section, but the Linker treats them independently. Each is 
assigned an absolute address such that they occupy mutually exclusive 
areas of memory. Named control sections, on the other hand, are 
treated globally. That is, if different object modules each have con- 
trol sections with the same name, they are all assigned the same ab- 
solute load address and the size of the area reserved for loading of 
the section is the size of the largest section. Thus, named control 
sections allow the sharing of data and/or programs among object mod- 
ules. This is similar to the handling and function of COMMON in 
FORTRAN IV. The names assigned to control sections are global and 
can be referenced as any other global symbol. 
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1 . 2 GLOBAL SYMBOLS 


Global symbols provide the links , or communication , between object mod- 
ules. With PAL— HR, these symbols would be created with the . GLOBL 
assembler directive. Symbols which are not global are called internal 
symbols. If the global symbol is defined (as a label or by direct as- 
signment) in an object module, it is called an entry symbol ,and other 
object modules can reference it. If the global symbol is not defined 
in the object module, it is an external symbol and is assumed to be 
defined (as an entry symbol) in some other object module. 

As the Linker reads the object modules it keeps track of all glo- 
bal symbol definitions and references. It then modifies the instruc- 
tions and/or data which reference the global symbols. 

1.3 RELINKING LINK-11 

Link-11 is provided as a system program with the PDP-11 Disk Operating 
System. 

It is available from DEC in the following formats: 

Absolute load module for 8K systems 
Object module for relinking 
ASCII source tapes 

These enable you to relink Link-11 using the supplied Link-11 load mod- 
ule to load into any 8K or larger system. The resulting Linker will 
assume a top of memory corresponding to the system configuration; 
this can be over-ridden using the T (top) or B (bottom) switches (see 
Section 3 . 2. 1. 1) . 

The top address assumed by the Linker is: 
nnn460 

where nnn is explained below. 

nnn for Memory Size 


37 

8K 

57 

12K 

77 

16K 

117 

20K 

137 

24K 

157 

28K 
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CHAPTER 2 


INPUT AND OUTPUT 


2.1 INPUT MODULE 

Link-11 1 s input is the object module. This is the output of the PAL-llR 
Assembler or any assembler or compiler that can produce an object mod- 
ule. The Linker reads each object module twice, thus, it is a two-pass 
processor. 

On pass 1, the Linker reads each object module to gather enough 
information so that absolute addresses can be assigned to all relocat- 
able sections and all globals can be assigned absolute values. This 
information appears in the global symbol directory (GSD) of the object 
module. 

On pass 2, the Linker reads all of each object module and produces 
the load module. The data gathered on pass 1 guides the relocation 
and linking process on pass 2. 

2.2 OUTPUT MODULE 

The normal output of the Linker is a load module which can be loaded 
and run. A load module consists of formatted binary blocks of absolute 
load addresses and object data as specified for the Absolute Loader 
and the DOS Monitor Loader. The first few words of data will be the 
communications directory (COMD) , and will have an absolute load address 
equal to the lowest relocated address of the program. 

2.2.1 Absolute Loader 

The Absolute Loader will load the COMD at the specified address, but 
then the program will overlay the COMD. The overlaying of the COMD by 
the relocated program allows the Absolute Loader to handle load modules 
with a COMD. However, a problem arises if a load module is to be loaded 
by the Absolute Loader and either of the following conditions exist: 

1. The object modules used to construct the load module 
contain no relocatable code, or 

2. The total size of the relocatable code is less than 
the size of the COMD. 
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In either case, there would not be enough relocatable code to overlay 
the COMD, which means that the COMD will load into parts of core not 
intended to be altered by the user. The Linker will select ‘the COMD's 
load address such that the COMD will be against the current top (see 
T switch in Section 3.2). If the top is very low, the Linker will not 
allow the COMD to be loaded below address 0 ; it will load it at 0. 

2.2.2 DOS Monitor Loader 

The DOS Monitor Loader will load the COMD where the Monitor wants it. 

The end of the load module will be indicated by a TRA (transfer address) 
block; that is, a block containing only a load address. The byte count 
in the formatted binary block will be 6 on this block; on all other 
blocks the byte count will be greater than 6. If the TRA is not speci- 
fied by a switch, it is assumed by the Linker to be the first even 
transfer address encountered. Thus, if four object modules are linked 
together and if the first and second have a .END statement without an 
address, the third a .END A, and the fourth a .END B, the transfer ad- 
dress would be A of module three. 

2.3 LOAD MAP 

The load map produced by Link-11 provides several types of information 
concerning the load module's make-up. The map begins with the transfer 
address and the low and high limits of the relocatable code. Then 
there is a section of the map for each object module included in the 
linking process. Each of these sections begins with the module's name 
followed by a list of the control sections and the entry points for 
each control section. For each control section, the base of the sec- 
tion (its low address) and its size (in bytes) is printed to the right 
of the section name (enclosed in angle brackets) . Following each sec- 
tion name is an alphabetically ordered list of entry points and their 
addresses. A list of any undefined symbols for each object module con- 
cludes the load map. 
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Note that modules are loaded such that if modules A, B, and C are 
linked together, A is lowest and C is highest in core. 


A sample load map is shown below. 
LOAD MAP 

TRANSFER ADDRESS: 037434 
LOW LIMIT: 037406 
HIGH LIMIT: 037460 
********** 


MODULE MODI 
SECTION ENTRY 
. ABS. 

X3 
X4 
X5 
X7 

**** ****** 

MODULE MOD 2 
SECTION ENTRY 

XI 
X2 

********** 

********** 

UNDEFINED REFERENCES 
X6 


ADDRESS SIZE 

0000013 000000 

037406 000044 

037430 

037440 

037452 

037450 


ADDRESS SIZE 
037452 000006 

037452 
037452 
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CHAPTER 3 


OPERATING PROCEDURES 


3.1 LOADING 

Link-11 is loaded into core by typing the following Monitor command. 
.RUN LINKll <CR > 


NOTE 

In the examples, typing the RETURN, LINE FEED, and 
SPACE keys are shown as <CR>, <LF>, and <SPACE>, 
respectively. Also, in the examples, program print- 
out is underlined whereas user typed input is not. 


When the Linker is in core and ready to accept the user's command, 
it prints the following three lines: 


LINK-11 V002A 

PAS SI 

# 


The user can now type a command string after the # sign. 


3.2 COMMAND STRING 

Commands are typed in response to the number sign, #, printed by the 
Linker. The format of the command string adheres to the requirements 
of the DOS Command String Interpreter (CSI) , as explained in the Disk 
Operating System Monitor, Programmer's Handbook. 

The Linker's file specifications must appear in the following 
order : 


#load module output, map output < object modules <CR> 

A null specification field signifies that the associated output 
is not desired. A complete specification contains the following in- 
formation : 


dev: f ilnam. ext [uic] /si: v/s2 : v. . ./sn:v <CR> 

The default values for each specification are noted below. 
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dev 

f ilnam 

ext 

uic 

Load Module 

DF0 

** 

LDA 

This user 

Map Output 

DF0* 

none 

MAP 

This user 

Object Module 

DF0* 

none 

OBJ 

This user 


*or last device specified on this side of the < 
**the filename from the first input specification 


If a syntactical error is detected in a command string, the Linker 
will print the command on the teleprinter up to and including the char- 
acter in error, followed by a question mark, and then a line beginning 
with the input request character #. The user can then type the command 
correctly. Link-11 performs this error reporting function on pass 1 
only. 

3.2.1 Switches 

There are nine switches associated with the Linker: 


/T Top 

/B Bottom 

/U Undefined globals 

/OD ODT 

/TA Tapes 

/CC Concatenate 

/TR Transfer address 

/E Exit 

/L Library 


The letter (s) representing each switch is always preceded by the slash 
symbol. Switches are not allowed in the output fields of a command 
string. 

3. 2. 1.1 Top and Bottom Switches 

The T and B switches are used to control the placement or relocation of 
the object program. When neither switch is specified, Link-11 will 
link the object programs to the top of available core, i.e., immediately 
below the Absolute and Boot Loaders. 

The T switch (top) can be specified with any of the input file 
specifications. It must be in the following format: 

/T:n 

where n is an unsigned octal number which defines a new top address. 

If a bottom is specified, the top switch is ignored. 


3-2 



The B switch (bottom) can be specified with any of the input file 
specifications. It must be in the following format: 

/B : n 

where n is an unsigned octal number which defines the bottom address 
of the object program. The B switch causes a top address to be calcu- 
lated so that the lowest address in the program will be at location n. 
If a top is specified, the bottom switch is ignored. 

Once a top of core has been calculated with the T or B switch, 
that value is used until it is changed. Only one T or B switch can be 
used during any one linking process. 

CAUTION 

The top or bottom value must be an unsigned 
even octal number. Link-11 detects if the 
value is odd and gives an error message. 

3. 2. 1.2 Undefined Globals Switch 

The U switch is used to obtain a teleprinter listing of all globals 
still found to be undefined at the time the switch is used. The listed 
globals will apply only to those files specified prior to the U switch 
request, including the specification in which the U itself appears. 

The U switch can be specified with any or all input file specifi- 
cations. Its format is: 

/U 

This switch does not require a value. 

3. 2. 1.3 Tapes Switch 

The TA switch is used to specify the number of tapes to be read in dur- 
ing the linking process. Its format is: 

/TA :n 

where n is an unsigned decimal number, the number of the tapes to be 
read. If n is too large, the user must load some dummy modules or put 
a blank tape in the reader for each extra request on both pass 1 and 
pass 2. 
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In response to this switch, the Linker requests the DOS Monitor 
to read n tapes from the specified input device. The Monitor will 
print : 


A002 063320 

$ 

whenever the device is not ready. The message A002 means that device 
063320 (high-speed paper tape reader, represented in Radix-5j2f) is not 
ready. 

The user should place the next tape in the reader and type CO<CR> 
in response to the $ printed by the Monitor to continue the linking 
process. The procedure above is repeated for each tape to be linked. 

After pass 1, the Linker will print PASS 2 and the procedure 
above is repeated, which produces the load module. After completing 
pass 2, control remains in the Linker for more link requests. 

3. 2. 1.4 Concatenate Switch 

The CC switch is used to indicate that the file was formed (by PIP) 
as a concatenation of several object modules. This switch must be 
placed with an input file specification. Its format is: 

/CC 

This switch does not have a value. 

3.2.1. 5 OPT Switch 

The OD switch is used to link ODT with your object modules. It must 
appear with ODT*s input file specification, in the following format: 

ODT . OBJ/OD 

which would identify the file as ODT, for transfer address purposes. 

3. 2. 1.6 Transfer Address Switch 

The TR switch can appear with any input file specification. It can 
be used with no value, or with an octal number or global symbol as its 
value. 
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When the TR switch has no value, it indicates that the Linker 
should take the transfer address (even or odd) of the first object 
module in the file as the transfer address of the load module. Its 
format is: 


/TR 

When it has an octal number as its value, it indicates that the 
value is the transfer address of the load module. Its format is: 

/TR:n 

When it has a global symbol as its value, it indicates that the 
value of the global symbol is the transfer address of the load module. 
Its format is: 

/TR: xxxxxx 

When the value is a nonexistent symbol, the transfer address is 
set to 1. 


3. 2. 1.7 Exit Switch 

The E switch should appear with the last input file specification. It 
indicates the end of input. 

3.2.1. 8 Library Switch 

The L switch is used to indicate that the file is a library. It must 
appear in an input file specification, if the specification contains a 
user library. The L switch has no value. Its format is: 

/L 

3. 2. 1.9 General Notes on Switches 

If a switch appears by itself as a specification (e.g. , , ,/CC) , it 

takes the default device and a file 0 file name. Thus, the linking 
process will be aborted if the default device requires a file. 

There are thirty words allowed for switches per input specifica- 
tion. If more are requested, it will result in a S203 error message. 
The following conditions also result in a S203 error message: 
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a. If a switch requires a value and if none appears 
or more than one appear. 

b. If a switch does not require a value and some 
value is given. 

Leader and trailer are punched on the load module when the output 
is to paper tape. The low-speed reader (LSR) and low-speed punch (LSP) , 
although able to be used by the Linker, are not serviced by the DOS 
for binary tapes. Therefore, they are considered illegal devices. 

A comprehensive summary of all switches appears in Chapter 5. 


3.3 LIBRARY SEARCHES 

3.3.1 User Libraries 

Object modules from the named user libraries built by the Libr-11 
Librarian will be relocated and linked by the Linker. The object 
modules in the libraries have to be ordered; only forward references 
are allowed. 

The libraries are input to the Linker as any other input file. 

The L switch in the input file specification indicates that this par- 
ticular file is a library. It has the following format: 

dev : libnam. ext/L 

For example, the user could type the following command string to 
the Linker: 

JTASK01 . LDA , LP : <MAIN ,MEASUR. LIB/L/E 

Program MAIN. OBJ would be read in from the disk as the first input 
file. Any undefined symbols generated by program MAIN. OBJ can be 
satisfied by the library MEASUR. LIB specified in the second input file. 

The load module, TASK01.LDA would be put on the disk, and a load map 
would go to the line printer. 

3.3.2 Monitor Library 

At the end of pass 1, the Monitor library is searched for Monitor 
routines which were declared as globals in the user program. Satis- 
fying these globals means that the Linker passes the EMT trap numbers 
of the found routines (in the COMD) to the Monitor so that at load time 
the Monitor brings the requested routines into core with the user program. 
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The user libraries are searched first and the Monitor library is 
searched last. 

3.4 AN EXAMPLE LINKING SESSION 

The Linker is called into core, identifies itself and prints # as 
explained in Section 3.1. The user could then type the first command 
string. For example: 

#PP : ,KB: <PR: <CR> 

which means that he wants the load module to be punched on the high- 
speed paper tape punch, the load map to be printed on the teleprinter, 
and his first object module to be read in from the high-speed paper 
tape reader. 

When the first tape is read in and no more file specifications 
follow, and when no E (Exit) switch has been seen by the Linker, the 
Linker asks for the next command string by printing another #. The 
user could now type: 

j|PR:/E<CR> 

The Linker would then read in the second input tape, encounter the Exit 
switch, and exit pass 1. The load map would then be printed on the 
teleprinter. 

When the Linker finishes printing the load map, it enters the 
second pass automatically to read in again the first tape from the 
paper tape reader. Before putting in the first tape again, wait until 
the Monitor prints: 

A002 063320 

$ 

where A002 means device 063320 (high-speed paper tape reader represen- 
ted in Radix-5,0) is not ready. The user then places the first tape in 
the reader, and in response to the $ printed by the Monitor he types: 

CO <CR> 

and the Linker starts processing the first tape. It then starts punch- 
ing out the load module. When finished reading the first tape, the 
Monitor prints: 
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Aft 02 06332ft 

? 


which again means that the paper tape reader is not ready. 

The user then places the second tape in the reader, and in response 
to the $ printed by the Monitor, he types: 

CO <CR> 

and the Linker starts processing the second tape. 

When the Linker finishes linking the two input tapes into one 
load module, it restarts itself and prints on the teleprinter: 

LINK-11 V002A 

PASS 1 
¥ 

and waits for another command string. 
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CHAPTER 4 


ERROR HANDLING AND MESSAGES 


4.1 RESTARTING 

The user can restart Link-11 at any time by typing 

CTRL/C RESTART or CTRL/C BEGIN 

which causes Link-11 to re-identify itself and print #. 

If the above sequence of keys (CTRL/C, RE (START) command, RETURN 
key) is typed while a load map is being printed, the load map will be 
aborted and the Linker will continue. 

4.2 WARNING ERROR MESSAGES 

The following three types of warnings are printed by Link-11. 

a. Non^unique object module name . This error is detected during 
pass 1 and results in the message: 

XXXXXX 

W 300 000000 

where XXXXXX is the non-unique object module name. The module is re- 
jected. The Linker will then continue processing the remaining unser- 
viced file specifications. 

b. A byte relocation error . The Linker will try to relocate 
and link byte quantities. Failure is defined as the high byte of the 
relocated value (or the linked value) not being all zero. In such a 
case, the value is truncated to 8 bits and the following message is 
printed : 


W 301 XXXXXX 

where XXXXXX is the absolute address where the byte relocation error 
occurred. The Linker automatically continues. 

c. Multiple-defined globals. This results during pass 1, 
causing the error message: 
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XXXXXX , YYYYYY 
VI302 000000 


where YYYYYY is the symbol which is multiple defined by object module 
XXXXXX. The second definition is ignored and the Linker continues. 

d. Undefined globals in the load module. This results at the 
end of pass 1, causing the error message: 

W322 000000 

meaning that there were some global symbols left undefined at the end 
of pass 1- The Linker then continues. 

4.3 ACTION REQUEST MESSAGES 

If the object modules are not read in from paper tape in the same order 
on pass 2 as on pass 1, the Linker will indicate which module should 
be loaded next by printing: 

XXXXXX 

Aj2fJ2f6 000000 

meaning, load object module XXXXXX next. 

When the message appears on the teleprinter, the Linker halts 
the creation of the load module temporarily. The tape which is in the 
paper tape reader is ignored. The Linker waits for the user to remove 
the incorrect tape and place the correct tape under the reader. 

When the user is done he types CO<CR> and the Linker reads in the 
tape and resumes the creation of the load module. 

If input comes from a file-structured device, this action request 
does not apply. 

4.4 FATAL LINKING ERROR MESSAGES 

When Link-11 detects a fatal error condition during the linking pro- 
cess, it prints an appropriate error message and then restarts itself. 
Fatal error messages and their meanings are listed below. 
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Error Message 
and Format 

S2j2f2 xxxxxx 
dev: f ile. ext 

S2)2f3 000000 

S 204 000000 

5206 000000 

5207 xxxxxx 

S21j2f 000000 
dev: file. ext 

5211 000000 
dev: file. ext 

5212 000000 
dev: file. ext 

S 213 000000 

dev: file. ext 

5214 000000 
dev: file. ext 

5215 000000 
dev : file. ext 

5216 000000 

5217 000000 

3220 000000 

module , symbol 
S223 000000 

S223 000000 

S225 000000 

S243 000000 


Meaning 


EOD or device error on .WRITE or .READ request, 
xxxxxx = error status byte. 

Illegal switch, or too many switches, or ille- 
gal switch value, or switch value not given, or 
switch in an output field. 

Too many output files. 

Input file not specified in CSI line. 

EOD or device error on .TRAN request. xxxxxx 
= error status byte. 

Unrecognized symbol table entry in indicated 
file. 

In indicated file, a RLD references a global 
name which cannot be found in the symbol table. 

In indicated file, a RLD contains a location 
counter modification command which is not last. 

In indicated file, an object module does not 
start with a GSD. 

In indicated file, the first entry in a GSD is 
not the module name. 

In indicated file, a RLD references a section 
name that cannot be found. 

The TRA specification references a nonexistent 
module name . 

The TRA specification references a nonexistent 
section name. 

An internal jump table index is out of range. 

Symbol table overflow. Insufficient space in 
symbol table for indicated symbol of indicated 
object module. 

No more space for CSI input buffer, or Monitor* s 
file manager routine, or for Monitor *s library 
search buffer. 

An angle bracket (<) in CSI line, which is not 
the first. 

Angle bracket ( <) is missing from the first CSI 
line. 
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CHAPTER 5 


SUMMARY OF LINK-11 SWITCHES 


Name 

Symbol 

Value 

Format 

Function 

Top 

T 

n (octal 
number) 

/T :n 

n becomes top of 
core 

Bottom 

B 

n (octal 
number) 

/B : n 

n becomes bottom 
of core 

Undefined 

Globals 

U 

none 

/u 

List undefined 
globals on tele- 
printer 

ODT 

OD 

none 

/OD 

This file is ODT 

Tapes 

TA 

n (decimal 
number) 

/TA:n 

There are n tapes 
to be read 

Concatenate 

CC 

none 

/CC 

This file contains 
concatenated ob- 
ject modules 

Transfer 

Address 

TR 

none 

/TR 

Take the transfer 
address of the 
first object mod- 
ule of this file 
as the transfer 
address 


TR 

n (octal 
number) 

/TR:n 

Take the octal 
number as the 
transfer address 


TR 

global 

symbol 

/TR: xxx xxx 

Take the value of 
the global symbol 
as the transfer 
address 

Library 

L 

none 

/L 

This file is a 
library 

Exit 

E 

none 

/E 

Exit from current 
pass ; end of link- 
ing 
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CHAPTER 6 


INTRODUCTION TO LIB R- 11 LIBRARIAN 


The PDP-11 Librarian (Libr-11) is a system program for the Disk Operat- 
ing System. Libr-11 provides facilities for creating, modifying, de- 
leting, and listing the contents of libraries. A library is a file 
which consists of one or mere object modules. (An object module is the 
binary output of the PAL-11R Assembler.) 

Libr-11 is a valuable program for the DOS user because: 


• It eliminates having separate directory 
entries in a User File Directory (UFD) 
for each object module. 

• It expedites the linking process in con- 
junction with the Linker's library search 
capabilities. 

• It allows for standardization and controlled 
updating of frequently used routines, e.g., 

FORTRAN cosine routine. 

The user controls the operation of Libr-11 through command strings 
typed on the keyboard. Specified in the command strings are such 
things as devices, library and object module names, and switches which 
indicate the Libr-11 operation desired. The user can direct Libr-11 
to j 


• Create a library 

• Update a library 

• Insert one or more object modules in a library 

• Replace one or more object modules in a library 

• List the contents of a library 

• Delete one or more object modules from a library 

• Delete an entire library 

A directory listing of the object modules of a library can be ob- 
tained merely by specifying the device on which the directory is to ap- 

pear and the name of the library. 

The flexibility of Libr-11 enables the user to specify certain 
combinations of operations in a single command string. For example, 
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a library can be modified, renamed, and listed in one command string. 


switch options 

which direct Libr-11' s operations 

Switch 

Operation 

/D 

Delete object module 

/DL 

Delete input library 

/I 

Insert object module 

/LO 

List object modules 

/R 

Replace object module 


If you type an illegal command string, e.g., illegal 
cessive switches, nonexistent file or object module, etc. 
print an appropriate error message on the teleprinter. 

The following discussion assumes that the reader is 
the DOS Monitor, Edit-11 Text Editor, PAL-1 1R Assembler, 
Debugging Program, and Link-11 Linker. 


are : 


format, ex- 
, Libr-11 will 

familiar with 
0DT-11R 
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CHAPTER 7 


OPERATING PROCEDURES, LIBR-11 


7. 1 CALLING LIBR-11 

The Librarian is called into core by typing the RUN command in response 
to the DOS Monitor 1 s dot or dollar sign. (The Librarian’s call name 
can be determined by listing the system directory using PIP.) The Li- 
brarian is often stored as LIBR, and when called it prints its name, 
version number, and a # sign, and then waits for the user to issue a 
command string. For example: 

^RUN LIBR <CR> 

LIBR-11 V001A 
i 

7.2 COMMAND STRINGS 

When the Librarian is in core and has printed the # sign, it is ready 
to accept a user command string. The format is: 

output library, listing file < input library, input file(s) 

Libr-11 performs two passes over all input files. For nonfile- 
structured devices (e.g. , paper tape reader) , the system will inform 
the user to reload the device for the second pass. For file-structured 
devices, both passes are performed automatically without requiring any 
user intervention. 

7.2.1 Creating a Library 

output library (, listing file) < , input file(s) 

A library is created on the device specified in the output library 
specification and named as specified. The listing file specification 
is optional and, if present, the contents of the output library will be 
listed. The format of the listing will be fully discussed later. 

An input library need not appear , but the comma and one or more 
input files must appear (each of which contains one or more object mod- 
ules*) . For example: 

#DT1:FIL.LIB< ,FIL.1,FIL. 2 <CR> 

*Note that an input file of concatenated object modules differs from a 
library in that it does not have a directory of the object modules that 
it contains. 
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would create a library named FIL.LIB on DECtape 1. The library would 
consist of all object modules in FIL.l and FIL.2 in that order, and 
in the order in which the object modules appear in their respective in- 
put files. 

7.2.2 Updating a Library 

Libraries can be updated in one of three ways: 

7.2. 2.1 To Delete One or More Object Modules 

output library (, listing file) < input library/D : : . . . 

The output library will be created as a result of deleting the object 
modules named v^...,v^ from the input library. The listing file is 
optional . 

The name associated with an object module is the symbol assigned 
to the module by PAL-llR's .TITLE assembler directive. 

The object modules to be deleted must appear in the same order 
as they appear in the library; their order can be determined from the 
listing. 

Insert and/or Replace operations cannot accompany a Delete request. 
For example: 

#DTl:LIBR.l < DT2 :LIBR0/D :Ml :M2 <CR > 

would create a library named LIBR.l on DECtape 1 as a result of delet- 
ing the object modules Ml and M2 from LIBR.0 on DECtape 2. 

7 . 2 . 2 . 2 To Insert One or More Object Modules 

output library (, listing file) <input library , input file (s) /I ( : v) 

The output library will be created as a result of inserting the object 
modules of the input file into the input library. If v is specified, 
the object module (s) in the input file are inserted starting at posi- 
tion v, otherwise, they are inserted at the end. v is treated as a 
decimal integer. 

If more than one input file is specified for insertion, the posi- 
tions at which they are to be inserted must appear in non-descending 
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order- For example: 


#DT1 : LIBR. 1<DT2 : LIBR. 0 , FIL. 1/1 :2 ,FIL. 2/1 < CR> 

would create an output library on DECtape 1 as a result of inserting 
the object modules of FIL.l into LIBR.0, beginning at position 2, and 
then inserting the object modules of FIL. 2 into LIBR.0 at the end. 

Insert and Replace operations can appear in the same command so 
long as the order restriction is observed. 

7. 2. 2. 3 To Replace One or More Object Modules 

output library (, listing file)<input library , input file(s)/R 

The output library will be created as a result of replacing the object 
module(s) in the input library by those in the input file(s). 

The object modules to be replaced must have the same name as those 
which replace them, and they must correspond orderwise. For example: 

#DT1 : LIBR. 1< DT2 : LIBR. j2f , FIL . 1/R, FIL . 2/R <CR> 

would create the output library LIBR. 1 on DECtape 1 as a result of re- 
placing the object modules in the input library LIBR.jZf with those in 
FIL.l and FIL. 2. 

7.2.3 Listing a Library 

, listing f ile (/L0)< input library 

The directory of the input library will be listed. Optionally, the 
presence of the /LO switch directs the Librarian to produce an object 
module listing. This is intended as a means to double-check the accur- 
acy of the library; the directory listing must correspond exactly 
to the object module listing. 

The output library will be listed when one was created; otherwise, 
the input library will be listed. The format of the listing is: 

Library Name & Extension 

Decimal Order Number Object Module Name (1st Module) 

Decimal Order Number Object Module Name (last module) 
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For example, if LIB . 1 contains object modules Ml, M2, and M3 
in that order, the command: 

£,LP : FIL. LST<DTl : LIB . 1 <CR> 

will produce on the line printer: 

FIL . LST 

jdjdjd01 Ml 

flfififi 2 M2 

PPPP3 M3 

If the /LO switch appears, for example: 

£, LP : FIL . LST/LCKDTl : LIB . 1 <CR> 

the listing above would be followed by a form feed and a similar table, 
except that the name of the second table is always OBJMOD.LST. 

The library name that is printed at the head of the listing is the 
name specified in the listing file specification. For example: 

fLIB . ABC , LP : NAME < , FIL . 1 , FIL . 2 <CR> 

The listing would be titled NAME, not the new created library LIB. ABC. 
When the listing file name is not specified, then the listing would be 
titled with the name of the newly created file. 


7 . 2 . 4 Naming Libraries 

The output library can have the same name as the input library. In 
this case, however, the input library has an implied /DL; that is, the 
input library is deleted. For example: 

#LIB . 1 <LIB . 1/D : 0M1 <CR> 

is the same as : 

#LIB . TMP< LIB . 1/D : 0M1/DL <CR> 

and then rename LIB.TMP to LIB.l. 
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CAUTION 


The user should never name a Library 
LIBR.TMP. This name is reserved for 
use by the Librarian. 


7.2.5 Legal File Specification Combinations 

In a command string, various combinations of file specifications are 
possible; legal combinations and their operation are shown below. 



Output 

Library 

Input 

Listing Library 

Input 
File (s) 

Operation 

Note 

Cl) 

P 

P 

P 

P 

Insert or Replace 
Object Modules; 
List Output Lib- 
rary 

SE if /D on 

input 

library 

C2) 

P 

P 

P 

NP 

Delete Object 
Modules; List 
Output Library 

SE if /D 
not on in- 
put library 

(3) 

P 

P 

NP 

P 

Create Library; 
List Output 

Library 

SE if switch 
on input 
file 

(4) 

NP 

P 

P 

NP 

List Input 

Library 

SE if /D 
on input 
library 

(5) 

P 

NP 

P 

P 

Same as (1) ex- 
cept no listing 

Same as 
(i) 

C6) 

P 

NP 

P 

NP 

Same as (2) ex- 
cept no listing 

Same as 
(2) 

C7) 

P 

NP 

NP 

P 

Same as (3) ex- 
cept no listing 

Same as 
(3) 


Legend: 

P = 
NP = 
SE = 

present 
not present 
syntax error 




7.3 EXAMPLES 

Assume FIL.l contains object modules 0M1, 0M2 , and 0M3 in that order, 
FIL.2 contains 0M4 and 0M5 in that order, FIL. 3 contains 0M5 and 0M3 
in that order, and FIL. 4 contains 0M6. Then: 


#LIB . 1 , LP : LIB . 1 <, FIL.l, FIL . 2 

will create a library named LIB.l containing object modules 0M1 , 0M2 , 
0M3 , 0M4 , and 0M5 in that order. The listing will appear on the line 
printer as : 
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LIB 


.1 


00001 0M1 

00002 OM2 

00003 OM3 

00004 OM4 

00005 OM5 

Files FIL.l and FIL.2 remain unaltered. The listing is produced after 
all other actions have been performed. Consequently , 

#LIB . 1 , LIB . 1 < t FIL . 1 , FIL. 2 <CR> 

would produce an error message (file already exists) when an attempt 
is made to write the listing to the disk. 

Using the assumption above: 

#LIB . 2<LIB . 1/D :0M1 :0M4 <CR> 

will create a library named LIB. 2 containing object modules 0M2 , 0M3 , 
and 0M5 in that order. No listing is produced and LIB.l is not de- 
leted. 

_#LIB . 3 <LIB . 2/D : 0M3 :0M2 <CR> 

will produce an error message because the modules to be deleted are 
not in the order in which they appear in the library. 


The command string: 


£,LP :LIB2. LS/LO<LIB .2 <CR> 


will produce a listing on the line printer which appears as: 


LIB2 .LS 

00001 0M2 

00002 0M3 

00003 0M5 
<form feed> 
OBJMOD.LST 

00001 0M2 

00002 0M3 

00003 0M5 
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The command string: 


#LIB . 3<LIB. 2/DL, FIL. 4/1 : 2 <CR> 

will create a library named LIB . 3 containing 0M2 , OM6 , 0M3 and 0M5 in 
that order. No listing is produced and LIB. 2 is deleted. 

The command string: 

#LIB . 4< LIB . 3 , FIL . 4/R <CR> 

will create a library named LIB. 4, which is really LIB. 3 with 0M6 re- 
placed (i.e., removed from LIB. 3 before creating LIB. 4). 

j|LIB . 5< LIB . 4 , FIL. 3/R <CR> 

will produce an error message because the object modules in FIL. 3 are 
not in the same order as in LIB. 4. 

The command string: 

#LIB . 5<LIB . 3/DL , FIL . 4/1 <CR> 

will create a library named LIB. 5 containing 0M2 , 0M6 , 0M3 , 0M5 and 
0M6 in that order- No listing is produced and LIB. 3 is deleted. Note 
that a library can contain multiple copies of the same object module, 
e.g., two 0M6 modules, above. 

The command string: 

#LIB - 6 <LIB . 5/D : 0M6 <CR> 

will create a library named LIB. 6 containing 0M2 , 0M3 , 0M5 and 0M6 in 
that order. No listing is produced and LIB. 5 is not deleted. When a 
library contains multiple copies of the same object module, they are 
deleted one at a time in their order of occurrence. 

If the purpose of the previous example were to delete all occur- 
rences of 0M6 , the command string would have been either: 

JLIB.6 <LIB. 5/D.-OM6 :0M6 <CR> 
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or 


#LIB . 6<LIB . 5/D:OM6/D:OM6 <CR> 

7. 4 ERROR MESSAGES 

Error messages issued by the Librarian are listed below. (See the DOS 
Monitor document for a listing of all DOS error messages.) 


Error 

Code 

Additional 

Information 

Meaning 

S202 

File Name and Error 
Status Byte 

Fatal I/O error; due to truncated 
line, checksum, character parity, 
or device parity error. 

S203 

File Name 

Switch error or semantic error; 
due to illegal switch, too many 
switches on a file, or illegal 
combination of file specifications. 

S204 


Illegal file specification format; 
more than two output files speci- 
fied. 

S 213 

File Name 

Error on input file; illegal ob- 
ject module format; first line not 
a GSD, or EOF prior to reading end 
module line. 

S244 

File Name 

Out of order; already past requested 
position for Insert. 

S245 

File Name 

Object module error; object module 
not found, or /R or /D out of order. 

S 24 6 


Error on input library; illegal lib- 
rary format, first two lines incor- 
rect. 

S247 


Listing error; output library cannot 
be read from output library device, 
i . e . , PP : . 
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HOW TO OBTAIN SOFTWARE INFORMATION 


Announcements for new and revised software, as well as programming notes, 
software problems, and documentation corrections are published by Software 
Information Service in the following newsletters. 

Digital Software News for the PDP-8 & PDP-12 
Digital Software News for the PDP-11 
Digital Software News for the PDP-9/15 Family 

These newsletters contain information applicable to software available from 
Digital's Program Library, Articles in Digital Software News update the 
cumulative Software Performance Summary which is contained in each basic 
kit of system software for new computers. To assure that the monthly Digital 
Software News is sent to the appropriate software contact at your installation, 
please check with the Software Specialist or Sales Engineer at your nearest 
Digital office. 

Questions or problems concerning Digital's Software should be reported to 
the Software Specialist. In cases where no Software Specialist is available, 
please send a Software Performance Report form with details of the problem to: 

Software Information Service 
Digital Equipment Corporation 
146 Main Street, Bldg. 3-5 
Maynard, Massachusetts 01754 

These forms which are provided in the software kit should be fully filled out 
and accompanied by teletype output as well as listings or tapes of the user 
program to facilitate a complete investigation. An answer will be sent to the 
individual and appropriate topics of general interest will be printed in the 
newsletter. 

Orders for new and revised software and manuals, additional Software Per- 
formance Report forms, and software price lists should be directed to the 
nearest Digital Field office or representative. U.S.A. customers may order 
directly from the Program Library in Maynard. When ordering, include the 
code number and a brief description of the software requested. 

Digital Equipment Computer Users Society (DECUS) maintains a user library 
and publishes a catalog of programs as well as the DECUSCOPE magazine 
for its members and non-members who request it. For further information 
please write to: 


DECUS 

Digital Equipment Corporation 
146 Main Street, Bldg. 3-5 
Maynard, Massachusetts 01754 
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